---
title: 환경 변수 사용
description: Astro 프로젝트에서 환경 변수를 사용하는 방법을 알아보세요.
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

Astro는 Vite에 내장된 환경 변수 지원을 사용합니다. 이를 통해 [Vite가 제공하는 모든 방법](https://ko.vitejs.dev/guide/env-and-mode.html)을 사용하여 환경 변수를 관리할 수 있습니다.

_모든_ 환경 변수는 서버 측 코드에서만 사용할 수 있으며, 보안을 위해 오직 `PUBLIC_` 접두사를 사용하는 환경 변수만이 클라이언트 측 코드에서 사용될 수 있습니다.

```ini title=".env"
SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there
```

이 예에서 `PUBLIC_ANYBODY`(`import.meta.env.PUBLIC_ANYBODY`를 통해 사용 가능)는 서버 측 코드와 클라이언트 측 코드에서 모두 사용할 수 있는 반면, `SECRET_PASSWORD`(`import.meta.env.SECRET_PASSWORD`를 통해 사용 가능)는 서버 측 코드에서만 사용할 수 있습니다.

:::caution
`.env` 파일은 [구성 파일](/ko/guides/configuring-astro/#환경-변수)에서 불러올 수 없습니다.
:::

## 기본 환경 변수

Astro는 기본적으로 몇 가지 환경 변수를 포함하고 있습니다.

- `import.meta.env.MODE`: 사이트가 실행 중인 모드입니다. `astro dev` 명령을 실행할 때는 `development`이고 `astro build` 명령을 실행할 때는 `production`입니다.
- `import.meta.env.PROD`: 사이트가 프로덕션 환경에서 실행 중인 경우 `true`입니다. 그렇지 않으면 `false`입니다.
- `import.meta.env.DEV`: 사이트가 개발 환경에서 실행 중인 경우 `true`입니다. 그렇지 않으면 `false`입니다. 항상 `import.meta.env.PROD`와 반대입니다.
- `import.meta.env.BASE_URL`: 사이트의 기본 URL입니다. 이는 [`base` 구성 옵션](/ko/reference/configuration-reference/#base)에 의해 결정됩니다.
- `import.meta.env.SITE`: 프로젝트의 `astro.config` 파일에 설정된 [`site` 옵션](/ko/reference/configuration-reference/#site)의 값입니다.
- `import.meta.env.ASSETS_PREFIX`: [`build.assetsPrefix` 구성 옵션](/ko/reference/configuration-reference/#buildassetsprefix)이 설정된 경우 Astro에서 생성된 자산 링크의 접두사입니다. 이는 Astro가 처리하지 않는 자산 링크를 생성하는 데 사용될 수 있습니다.

다른 환경 변수처럼 사용하세요.

```ts utils.ts
const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;
```

## 환경 변수 설정

### `.env` 파일

환경 변수는 프로젝트 디렉터리의 `.env` 파일에서 불러올 수 있습니다.

`.env.production` 또는 `.env.development`처럼 파일 이름에 모드(`production` 또는 `development`)를 추가할 수도 있습니다. 이렇게 하면 환경 변수가 해당 모드에서만 적용됩니다.

프로젝트 디렉터리에 `.env` 파일을 생성하고 몇 가지 변수를 추가하세요.

```ini title=".env"
# 서버에서 실행될 때만 사용할 수 있습니다!
DB_PASSWORD="foobar"
# 어디서나 사용할 수 있습니다!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"
```

`.env` 파일에 대한 자세한 내용은 [Vite 문서](https://ko.vitejs.dev/guide/env-and-mode.html#env-files)를 참조하세요.

### CLI 사용

프로젝트를 실행할 때 환경 변수를 추가할 수도 있습니다.

<PackageManagerTabs>
 <Fragment slot="yarn">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev
    ```
 </Fragment>
 <Fragment slot="npm">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev
    ```
 </Fragment>
 <Fragment slot="pnpm">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev
    ```
 </Fragment>
</PackageManagerTabs>

:::caution
이 방법으로 설정된 변수는 클라이언트를 포함하여 프로젝트의 모든 곳에서 사용할 수 있습니다.
:::

## 환경 변수 가져오기

Astro의 환경 변수는 process.env 대신 [ES2020에 추가된 import.meta 기능](https://tc39.es/ecma262/2020/#prod-ImportMeta)의 import.meta.env를 통해 사용할 수 있습니다.

예를 들어 `import.meta.env.PUBLIC_POKEAPI`를 사용하여 `PUBLIC_POKEAPI` 환경 변수를 가져올 수 있습니다.

```js /(?<!//.*)import.meta.env.[A-Z_]+/
// import.meta.env.SSR === true인 경우 사용됨
const data = await db(import.meta.env.DB_PASSWORD);

// import.meta.env.SSR === false인 경우 사용됨
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);
```

SSR을 사용하는 경우, 사용 중인 SSR 어댑터를 통해 런타임 시 환경 변수를 사용할 수 있습니다. 대부분의 어댑터는 `process.env`를 통해 환경 변수를 사용하지만 일부 어댑터는 다르게 동작합니다. Deno 어댑터의 경우 `Deno.env.get()` 함수를 사용합니다. [Cloudflare 런타임 사용](/ko/guides/integrations-guide/cloudflare/#cloudflare-런타임)에서 Cloudflare 어댑터가 환경 변수를 처리하는 방법을 알아보세요. Astro는 먼저 서버 환경에서 변수를 확인하고 변수가 존재하지 않으면 .env 파일에서 해당 변수를 찾습니다.

## TypeScript 자동 완성

기본적으로 Astro는 `astro/client.d.ts` 파일에서 `import.meta.env`에 대한 타입 정의를 제공합니다.

`.env.[mode]` 파일에서 더 많은 사용자 정의 환경 변수를 정의할 수도 있지만, `PUBLIC_` 접두사를 사용하여 사용자 정의 환경 변수를 위한 TypeScript 자동 완성을 얻고 싶을 수도 있습니다.

이를 위해 `src/` 디렉터리에 `env.d.ts` 파일을 생성하고 다음과 같이 `ImportMetaEnv` 인터페이스를 구성할 수 있습니다.

```ts title="src/env.d.ts"
interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // 더 많은 환경변수 ...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```
